1 Introduction

• You can download the workshop material on github.

• Don’t hesitate to comment (new issues), or request changes (pull request) on .

• Follow the .html (web browser) and the .Rmd (Rstudio) documents. Try and experiment.

• ~2 hours: Introduction and practice

• ~15 minutes: pause

• ~1 hour: other formats (.docx, .pdf). Workshop here

• ~15 minutes: shiny. Workshop here

2 Markdown

• Markdown is a lightweight markup language with plain text formatting syntax (Easy-to-read, easy-to-write plain text format). It is designed so that it can be easily converted to HTML and many other formats (e.g. PDF, MS Word, .docx).

• Like other markup languages (e.g. HTML and Latex), it is completely independent from R.

• Typically, file have the extension .md.

• Look at this example. Examine the html render (github automatically interprets .md files) and raw file.
  

3 R Markdown

• An extension of the markdown syntax that enables R code to be embedded and executed.

• Generate fully reproducible reports in different of static and dynamic output formats.

• Most of these packages are maintained by the Rstudio team (https://rmarkdown.rstudio.com/, Yihui Xie)

• Plain text files that typically have the file extension .Rmd.

• So, how does it work:

  • Write text & code in Rstudio.

  • Knit: The R package rmarkdown feeds the .Rmd file to the R package knitr.

  • knitr executes code and creates a new markdown (.md) document which includes the code and output.

  • Subsequently tranformed into .html/.tex/.docx by pandoc. (Note that .tex files need to be transformed by pdflatex into .pdf files. We’ll come back to that later.)

  • Pandoc is an universal document converter, independent of R.

  • By default, Rstudio comes with rmarkdown, knitr, and pandoc (but not pdflatex).

  • When you click the Knit button (top left), a document will be generated that includes both content as well as the output of R code within the document.
    

4 R markdown syntax

• Markdown provides an easy way to make standard types of formatted text, like:

  • italics (*text*) or italics (_text_)

  • bold (**bold**)

  • backslash (\) to interpret a special characters as character

  • # and space at the beginning of line for a header level (6 levels, # to ######)

  • bold italic (_**bold italic**_)

  • links ([links](https://www.rmarkdown.rstudio.com))

  • Two spaces for a newline character

  • “ ” character (html Non-Breaking SPace) for extra line spacing can be useful.

  • list (first element using * and space, then idented (tab or 2 spaces) * and space)
    • item 1a
    • item 1b

  • quoted text (`quoted text`)

> Quoted text: 1st way
> more quoted text
> still more quoted text

Quoted text: 1st way
more quoted text
still more quoted text

`Quoted text: 2nd way`
`more quoted text`
`still more quoted text`

Quoted text: 2nd way
more quoted text
still more quoted text

```
text: 3rd way
quoted text
more quoted text
```

Quoted text: 3rd way    
more quoted text         
still more quoted text        

• Tables

Species | Counts
——— | —–
H. sapiens | 24
M. musculus | 442

• The cheatsheet v1 or v2 is your friend.

5 Header

---  
title: "Rmarkdown"  
author: "Sebastien Renaut"  
date: '2018-03-12'  
output: html_document  
---  

• Header, metadata, YAML, YAML Ain’t Markup Language (https://en.wikipedia.org/wiki/YAML#History_and_name) ?

• Header specifies configurations (what kind of document will be created, and the options chosen).

• It is not required (defaults then apply).

• It uses Python-style indentation to specify certain options.

• Many options possible depending what type of document you are generating. See below for some examples.

• Note that some options can be specified either for the whole document (in the header), the code chunks, or both (chunks options supersede header). More on code chunks later.

6 Customizing header

---  
title: "Rmarkdown"  
author: "Sebastien Renaut"  
date: "February 27, 2019"   
output: 
#pdf_document:
 html_document:  
   highlight: tango  
   number_sections: T  
   theme: united 
   toc: yes  
   toc_depth: 3  
---  

• Note the indentation in the .Rmd document for the output options.
• Note the # symbol to comment out option.
  
• Note that date is population via an R function

# Preface {-}

7 Code chunks

• The real power of R Markdown comes from mixing markdown with chunks of code.

• A code chunk is intepreted by knitr. It works essentially the same as the R syntax we are familiar with.

• A main code chunks may look like this:

```{r code chunk example, include = T, message = T, warning=T, echo = T, fig.cap="Figure 1"}  
#Running some R code.
x = rexp(1000)  
min(x)  
max(x)  
plot(x)  
```    

• On the 1st line, I specify that I will run the R programming language.

• Then, I give the chunk a UNIQUE name and specify options.

• Here are common options:

  • include = F: Code and results will NOT appear in the finished file. Code is still interpreted, and the results can be used by other chunks.

  • echo = FALSE prevents code, but not results from appearing in the finished file. This is a useful way to embed figures.

  • message = FALSE prevents messages that are generated by code from appearing in the finished file.

  • warning = FALSE prevents warnings that are generated by code from appearing in the finished file.

  • fig.cap = "..." adds a caption to graphical results.

  • fig.width=..., fig.height=... can also change figure width/heigth.

• By default R studio creates a Global Options code chunk. Let’s examine this chunk:

```{r setup, include=FALSE}  
knitr::opts_chunk$set(echo = TRUE)  
```  

• see cheat sheet for more info.

• Note that you also run inline code using the using the ` ` symbols and specifying the programming language. For example, ` r 10+5 ` would be processes as 15.

```{bash, echo = F}
ls -1
```

## rmarkdown_main.Rmd
## rmarkdown_main.html
## rmarkdown_main.log
## rmarkdown_main.tex
## rmarkdown_word_pdf.Rmd
## rmarkdown_word_pdf.html
## rmarkdown_word_pdf.pdf
## rmarkdown_word_pdf.tex
## rsconnect
## shiny.Rmd
## test.Rmd
## test.html

```{python, echo = F}
x = "hello python!"
print(x.split(' '))
```

## ['hello', 'python!']

```{perl, echo = F}
print "Hello perl!";
```

## Hello perl!

8 Include pictures & figures.

• There are several ways to include figures.

• Can be included from an URL directly uploaded from the web:
  ![optional caption here](https://static.independent.co.uk/s3fs-public/styles/article_large/public/thumbnails/image/2017/09/12/11/naturo-monkey-selfie.jpg){width=250px}

• If this figure is small, it can be added to the text directly: eg.: Today, we are using to generate webpages with images…

• This is a graph previously saved in the figures directory
  ![](../figures/DEG_heatmap.png){width=250px}
   

• In all these cases, graphs are rendered with pandoc and not knitr, so pandoc options need to be specified, not R graphics options:

  • It’s simple, but options are tricky.

  • You may need to play with spacing, figure size, and figure position.

  • Options are specified directly after the URL or link (eg. {width=250px} or {width=50%}).

• Images can also be interpreted by knitr as below:

```{r graphic_example, out.width = "20%", fig.cap = "An orange man", echo = F,fig.align = "center"}  
knitr::include_graphics("../figures/orange.jpeg")  
```

An orange man

• Graphs can also be generated directly by R code, specified in a code chunk (R options specified in the code chunk) and interpreted by knitr as we did previously.

```{r another example, echo = T, message = F}
library(ggplot2)
mtcars_ggplot = ggplot(mtcars, aes(x=wt, y=mpg)) + 
geom_point() + geom_smooth()
mtcars_ggplot
```

library(ggplot2)
mtcars_ggplot = ggplot(mtcars, aes(x=wt, y=mpg)) + 
geom_point() + geom_smooth()
mtcars_ggplot

9 Including Tables

• By default, R Markdown displays data frames and matrices as they would be in the R terminal (in a monospaced font).

• You can use the knitr::kable function for additional formatting, as in the .Rmd file below.

#Default R printout (ugly)
print(head(mtcars))

##                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
## Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
## Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
## Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
## Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
## Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
## Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

#With kable function from knitr (better looking)
knitr::kable(head(mtcars),digits =1,caption = "A motorcars table")

10 Citations, footnotes, bibliography

• Footnotes are easy when you have a few references. Use [^1] and add reference at the end using same format.¹

• Otherwise, you may specify a bibliography and citation style in the header.

---  
csl: csl/peerj.csl  
bibliography: biblio/test_library.bib  
---

• The Citation Style Language (.csl) file specifies the reference format.

• It is an open XML-based language to describe the formatting of citations and bibliographies. Reference management programs using .csl include Zotero, Mendeley and Papers.

• Most journals should have a .csl file be on this github repo. But you could create your own.

• A .bib file contains the bibliographic information of your document.

• Here, I created a a .bib file in the reference management software Papers3.

• But now, I often copy .bib reference directly from google scholar.
  

11 Cheatsheets and help

• Lessons

• Book
  • This is a great reference. In addition, it is (of course) written in R mardown and publicly available on GitHub. As such, if you see something you like, go see how it was written in .Rmd!

• Cheatsheet (old - short)

• Cheatsheet (newer - longer)

• Pimp my Rmd

• Stack Overflow

12 References

(Note that references below are generated automatically, except for the footnote.)